… 6 registry-listing

User-facing front-door rewrite plus a new "Phase 6 — Distribution
surface" requirement in the plan that records the MCP-registry
listing as a maintained shipping channel. Master architecture doc
gets a §4.6 growth-playbook entry covering the same and a §6 ref
to the official registry + the new users guide.

### docs/ai-discoverability/ai-users-guide.md — rewrite

* Title shifted from "AI user's guide" to "users guide" — the doc
  now serves both audiences explicitly.
* Table of contents at the top with anchored links.
* §1 What's available — three artifacts (llms.txt + tools.json +
  task_index.json) + the MCP server + the registry-listing call-out
  (io.github.m-dev-tools/m-dev-tools-mcp).
* Part A — For humans (developers + teams):
  * A.1 Quickest path — three install options:
    Option 1 GitHub Copilot Chat in VS Code
      (.vscode/mcp.json, agent mode)
    Option 2 Claude Code (.mcp.json, terminal or extension)
    Option 3 Registry-driven (any client that consults the official
      MCP registry — Codex, Continue, Goose, …; no hand-rolled
      .mcp.json)
  * A.2 Alternative: direct catalog access (no MCP).
  * A.3 Smoke-test the wiring.
  * A.4 Troubleshooting table.
  * A.5 Reporting issues — which tracker per bug class.
* Part B — For AI agents (reading this in-session):
  * B.1 Tools available (route_intent / describe / verify) with
    the JSON-schema-on-connect note.
  * B.2 Typed-ID grammar + what describe returns per kind.
  * B.3 Example session (route_intent → describe → fetch manifest
    → cite the URL).
  * B.4 What you WILL and WILL NOT do, including the "verify
    doesn't execute" security stance.
  * B.5 Fallback: raw-catalog 8-step handshake.
* §3 Shared "Where to learn more" — links to the architecture doc,
  plan, guide, phase docs, MCP-server repo, and the registry entry.

### AI-discoverability-plan.md — new "Phase 6"

Phase 6 spells out the distribution-surface broadening as a
required ship beyond Phase 5:

1. Official MCP registry listing via `mcp-publisher publish` from
   the m-dev-tools-mcp repo. A server.json lands at the repo root;
   the CLI submits it to registry.modelcontextprotocol.io. Once
   listed under io.github.m-dev-tools/m-dev-tools-mcp, registry-
   aware clients auto-discover without .mcp.json config.
2. Maintenance: every release tag triggers `mcp-publisher publish`
   from a GitHub-Actions workflow.

Optional (deferred): PyPI (same rationale as §5.3 — irreversible
namespace claim, defer until external adoption demands it); a VS
Code extension sibling to tree-sitter-m-vscode / m-stdlib-vscode
for the VS Code / Cursor-specific audience.

Exit criterion: a fresh-install MCP-capable client points at the
registry and resolves the canonical `route_intent` query without
client-side config.

### AI-discoverability-architecture.md — new §4.6 growth playbook

§4.6 "Ship the MCP server through a new distribution channel" —
the maintainer's recipe for adding a new channel (PyPI, VS Code
extension, Homebrew tap, …) on top of the registry-listing pattern.
Notes that mcp-publisher login github + publish needs human at a
browser; GitHub OIDC mode is the CI-automation path for later.

§6 Where to read more — added the registry pointer
(`registry.modelcontextprotocol.io` /
`io.github.m-dev-tools/m-dev-tools-mcp`) on the m-dev-tools-mcp
bullet, and added the users guide as its own list item.

### Verified

* make check-docs-prose / check-freshness / check-links /
  check-licenses / check-schema-compat / recipes-check /
  handshake / validate-catalog — all clean.

### What's next (separate PR + manual step)

* PR 2 on m-dev-tools-mcp: add server.json at repo root +
  publish-on-tag GitHub Action.
* Manual step: maintainer runs `mcp-publisher login github` +
  `mcp-publisher publish` from a clean clone (browser OAuth; can't
  be scripted from here).

The original AI-discoverability-plan.md §5.3 deferred PyPI publication
"until external usage validates the API + name". Phase 4 shipped
v0.1.0 via the GitHub-Release wheel path and got real agent use
without a regretted publish. Phase 6 planning then surfaced a
constraint: the official MCP registry only accepts packages from
NPM / PyPI / NuGet / Docker-OCI / MCPB. A `uvx --from git+...`
install isn't accepted.

Decision (2026-05-11): reverse the deferral. Publish to PyPI;
declare the PyPI entry in the registry-listing server.json. The
"permanent namespace" concern that drove the original deferral is
now mitigated — the v0.1.0 API surface (route_intent / describe /
verify) is exactly what shipped to real agents in Phase 4, so the
PyPI commit is no longer speculative.

### Plan doc — §5.3 rewritten

The "Distribution: GitHub-first, not PyPI" paragraph now reads
"Originally GitHub-Release-wheel-only (Phase 4 v0.1.0 shipped that
way); the PyPI deferral was reversed at Phase 6 planning because
publishing to the official MCP registry requires the server be
reachable through a registry-supported channel." Three install
paths surfaced in recommended order: PyPI (primary, what the
registry references), GitHub Release wheel (backup), git+url via
uvx (pre-release testing).

### Plan doc — Phase 6 rewritten

The "Required ships" list now has three entries: (1) PyPI
publication via `uv publish`; (2) MCP registry listing via
`mcp-publisher publish` referencing the PyPI entry; (3)
release-tag maintenance workflow that does both. The "Optional
deferred" list drops PyPI (no longer deferred) and keeps only the
VS Code extension as a future possibility.

### Plan doc — §7 Phase-4 + §10 distribution table

Phase-4 description note: now reads "PyPI follows in Phase 6 once
registry-listing requires it (Phase 4 closed pre-PyPI per the
original §5.3 deferral; §5.3 was updated at Phase 6 planning to
reverse the deferral)." Distribution table's m-dev-tools-mcp row
rewritten to list all three channels + the registry listing.

### Architecture doc — §1.2 + §4.6

§1.2 "What MCP clients need on top of discovery" — the
frictionless-install bullet now lists `pip install
m-dev-tools-mcp` first, then the wheel and uvx paths. The "No
PyPI registration" sentence is gone.

§4.6 "Ship the MCP server through a new distribution channel" —
the lead paragraph now says four channels (PyPI / GH-Release
wheel / uvx / MCP registry) and the maintainer recipe drops PyPI
from the "to add a new channel" example.

### Users guide — new Option 0 under §A.1

Added "Option 0 — PyPI (works for any MCP client that points at a
binary on $PATH)" at the top of §A.1, with `pip install
m-dev-tools-mcp` + the resulting one-line `.mcp.json` /
`.vscode/mcp.json` config. Existing Options 1-3 remain as
fallbacks; phrasing notes Option 0 is the recommended path once
m-dev-tools-mcp is on PyPI (Phase-6 ship).

### Verified

* make check-docs-prose / check-freshness / check-links /
  check-licenses / check-schema-compat / recipes-check /
  handshake / validate-catalog — all clean.

### What lands next (out of this PR)

PR 2 on m-dev-tools-mcp: server.json with `registryType: pypi` at
the repo root + a `release.yml` GitHub Action that does `uv build`
+ `uv publish` (Trusted Publisher OIDC) + `mcp-publisher publish`
(GitHub OIDC) on every `v*` tag.